Can we get a race condition here?

I assume you are concerned about the caching and restoring of the _readyPromise in lines 944, 945, and 953 below.

Here's how I understand the situation. First, ignore the machine for a moment, and just think about this as

public whenReady(action: () => any): Promise<any> {
    return (this._readyPromise = this._readyPromise.then(() => action());
}

which is what it would be without the caching of the promise. In that case, as long as action() doesn't call a function that calls whenReady(), I think you will agree that this will serialize the calls to whenReady(). (The _readyPromise property is protected and the only function that changes it is whenReady().) So a question only arrises when action() calls a function that itself uses whenReady().

Note that if multiple whenReady() calls are made, the actions will be queued, and not executed immediately. For example, if md is a MathDocument

md.whenReady(() => console.log('A'));
md.whenReady(() => console.log('B'));
md.whenReady(() => console.log('C'));
console.log('queued');

will produce

queued
A
B
C

If the action() creates a promise, it should return that promise so that whenReady() will in term wait for that promise to complete. So, for example

md.whenReady(() => console.log('A'));
md.whenReady(() => new Promise((ok, fail) => setTimeout(() => {console.log('B'); ok()}, 1000)));
md.whenReady(() => console.log('C'));
console.log('queued');

will produce the same output as above, but with a 1 second wait before the B is produced.

Similarly, for an asynchronous function that uses await, which returns a promise automatically, whenReady() will wait for the async function to finish. Thus

const promise = new Promise((ok, fail) => setTimeout(ok, 1000));
md.whenReady(() => console.log('A'));
md.whenReady(async () => {await promise; console.log('B')});
md.whenReady(() => console.log('C'));
console.log('queued');

produces the same results. So as long as action() returns the promise it creates, all is well.

The complication comes when action() calls a function that itself uses whenReady() (or calls it directly). Consider, for example:

md.whenReady(() => console.log('A'));
md.whenReady(() => md.whenReady(() => console.log('B')));
md.whenReady(() => console.log('C'));
console.log('queued');

Here, we get the queued message and the A, but nothing else. In this case when the queued message is produced, all three actions have been but none of them performed, yet, and the _readyPromise is the one that resolves when the third action is complete (when console.log('C') is performed).

At this point, the _readyPromise looks like

Promise.resolve()
  .then(() => console.log('A'))
  .then(() => md.whenReady(() => console.log('B')))
  .then(() => console.log('C'));

and none of the then actions have been taken. Now when javascript becomes idle, the first then is executed, and the A is printed and its promise is resolved, so the next then can be performed.

At this point, the inner whenReady() function is called, and adds is action to then for the _readyPromise , so at the end of the list above, and then returns that promise to that second then in the list above. That means the then will wait for that promise to complete before it resolves; but because that promise follows the last one in the list above, it will not resolve until the previous ones do. That means we are in a catch-22 and the list will stop at this point with no additional actions ever being performed.

It is that situation that is being handled by adding the caching of the _readyPromise. With that in place, each of the then functions above first cache the promise, replace it with Promise.resolve(), call the action currently listed in the then saving its result, puts back the promise, and returns the saved result. This has no effect on the first and third actions, but the middle one is changed so that when the whenReady() function runs, rather than adding its action to the end of the current list, it adds its action to a new Promise.resolve() and returns that. That is, the second action now effectively returns

Promise.resolve().then(() => console.log('B'));

That is the value saved as the result at line 949, and then the _readyPromise is returned to its original value. Because this result is a promise, the second then in the list above will wait for that promise to resolve before it is resolved itself. That means that when javascript is next idle, the console.log('B') will be performed, then the promise listed just above from the whenReady() will resolve, and that allows the second then to resolve. That means the final then can be performed, allowing the console.log('C') to execute. This effectively breaks the lock-out situation that occurred originally.

Because the cached _readyPromise is put back directly after calling action(), and because no idle tasks can be performed between saving the promise and putting it back (only the top-level code from action() can run, not any of its promises), no race condition exists, and any other whenReady() functions that aren't within the action() will find the _readyPromise to be as though it had never been changed. And as long as the action() function returns any promises that it receives from whenReady() calls (or the promises from other functions that call whenReady()), the actions will be properly serialized. Note also that whenReady() calls can be nested to any depth with this strategy.

If action() fails to return a promise, as, for example, with

md.whenReady(() => console.log('A'));
md.whenReady(() => {md.whenReady(() => console.log('B'))});
md.whenReady(() => console.log('C'));
console.log('queued');

where the second then doesn't return the promise from the nested whenReady() call, then console.log('C') will run before console.log('B'), since the former was added to its then before the latter was added to the Promise.resolve() that replaced the _readyPromise chain, and these two are not tied together by a common promise chain. That could cause a potential intermingling of the actions. I would consider not returning the promise from whenReady() to be a bug in the action() code for that reason.

While writing this, I realized that there is a way to avoid even that issue. Changing lines 950 through 960 to

      //
      // Get a promise that returns the result after
      // any new _readyPromise resolves (in case action
      // called whenReady() or another function that does).
      //
      const promise = this._readyPromise.then(() => result);
      //
      // Put back the original promise.
      //
      this._readyPromise = ready;
      //
      // Return promise that returns the result.  The original
      // _readyPromise will wait on it to complete before it resolves,
      // since promises that return promises automatically chain.
      // This inserts any new _readyPromise promises into the
      // original _readyPromise chain at this point.
      //
      return promise;

would make sure that any new _readyPromise promises are resolved before the result gets returned. That effectively injects any new _readyPromise chain into the original chain at the current location rather than at the end, thereby avoiding the lock-out situation that we saw above.

I will make a new commit for that change.